﻿// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace System.Diagnostics.CodeAnalysis;

/// <summary>
///  Suppresses reporting of a specific rule violation, allowing multiple suppressions on a
///  single code artifact.
/// </summary>
/// <remarks>
///  <para>
///   <see cref="UnconditionalSuppressMessageAttribute"/> is different than <see cref="SuppressMessageAttribute"/> in
///   that it doesn't have a <see cref="ConditionalAttribute"/>. So it is always preserved in the compiled assembly.
///  </para>
/// </remarks>
[AttributeUsage(AttributeTargets.All, Inherited = false, AllowMultiple = true)]
#if SYSTEM_PRIVATE_CORELIB
public
#else
internal
#endif
sealed class UnconditionalSuppressMessageAttribute : Attribute
{
    /// <summary>
    ///  Initializes a new instance of the <see cref="UnconditionalSuppressMessageAttribute"/>
    ///  class, specifying the category of the tool and the identifier for an analysis rule.
    /// </summary>
    /// <param name="category">The category for the attribute.</param>
    /// <param name="checkId">The identifier of the analysis rule the attribute applies to.</param>
    public UnconditionalSuppressMessageAttribute(string category, string checkId)
    {
        Category = category;
        CheckId = checkId;
    }

    /// <summary>
    ///  Gets the category identifying the classification of the attribute.
    /// </summary>
    /// <remarks>
    ///  <para>
    ///   The <see cref="Category"/> property describes the tool or tool analysis category
    ///   for which a message suppression attribute applies.
    ///  </para>
    /// </remarks>
    public string Category { get; }

    /// <summary>
    ///  Gets the identifier of the analysis tool rule to be suppressed.
    /// </summary>
    /// <remarks>
    ///  <para>
    ///   Concatenated together, the <see cref="Category"/> and <see cref="CheckId"/>
    ///   properties form a unique check identifier.
    ///  </para>
    /// </remarks>
    public string CheckId { get; }

    /// <summary>
    ///  Gets or sets the scope of the code that is relevant for the attribute.
    /// </summary>
    /// <remarks>
    ///  <para>
    ///   The Scope property is an optional argument that specifies the metadata scope for which
    ///   the attribute is relevant.
    ///  </para>
    /// </remarks>
    public string? Scope { get; set; }

    /// <summary>
    ///  Gets or sets a fully qualified path that represents the target of the attribute.
    /// </summary>
    /// <remarks>
    ///  <para>
    ///   The <see cref="Target"/> property is an optional argument identifying the analysis target
    ///   of the attribute. An example value is "System.IO.Stream.ctor():System.Void".
    ///   Because it is fully qualified, it can be long, particularly for targets such as parameters.
    ///   The analysis tool user interface should be capable of automatically formatting the parameter.
    ///  </para>
    /// </remarks>
    public string? Target { get; set; }

    /// <summary>
    ///  Gets or sets an optional argument expanding on exclusion criteria.
    /// </summary>
    /// <remarks>
    ///  <para>
    ///   The <see cref="MessageId "/> property is an optional argument that specifies additional
    ///   exclusion where the literal metadata target is not sufficiently precise. For example,
    ///   the <see cref="UnconditionalSuppressMessageAttribute"/> cannot be applied within a method,
    ///   and it may be desirable to suppress a violation against a statement in the method that will
    ///   give a rule violation, but not against all statements in the method.
    ///  </para>
    /// </remarks>
    public string? MessageId { get; set; }

    /// <summary>
    ///  Gets or sets the justification for suppressing the code analysis message.
    /// </summary>
    public string? Justification { get; set; }
}
